package com.gitee.qdbp.general.common.api.files.service;

import java.io.File;
import java.io.InputStream;
import com.gitee.qdbp.able.exception.ServiceException;
import com.gitee.qdbp.general.common.api.files.model.FileAuthorization;
import com.gitee.qdbp.general.common.api.files.model.IPathParams;

/**
 * WEB文件服务<br>
 * IPathParams主要是用于按业务类型分开保存数据, 只有在实际上传时才能确定根路径的名称, 而不能提前配置<br>
 *
 * @author zhaohuihua
 * @version 160218
 */
public interface IWebFileService {

    /**
     * 上传文件
     *
     * @param file 文件
     * @return 文件服务器地址
     */
    String upload(File file) throws ServiceException;

    /**
     * 上传文件
     *
     * @param extension 文件扩展名, 如.png, 也可以是文件全路径, 会自动截取扩展名
     * @param bytes 文件内容
     * @return 文件服务器地址
     */
    String upload(String extension, byte[] bytes) throws ServiceException;

    /**
     * 上传文件
     *
     * @param extension 文件扩展名, 如.png, 也可以是文件全路径, 会自动截取扩展名
     * @param input 文件流
     * @param size 文件大小
     * @return 文件服务器地址
     */
    String upload(String extension, InputStream input, long size) throws ServiceException;

    /**
     * 上传文件
     *
     * <pre>
     * fileService.upload(FolderName.files, file);
     * </pre>
     *
     * @param params 文件上传根路径
     * @param file 文件
     * @return 文件服务器地址
     */
    String upload(IPathParams params, File file) throws ServiceException;

    /**
     * 上传文件
     *
     * <pre>
     * fileService.upload(FolderName.files, ".png", bytes);
     * </pre>
     *
     * @param params 文件上传根路径
     * @param extension 文件扩展名, 如.png, 也可以是文件全路径, 会自动截取扩展名
     * @param bytes 文件内容
     * @return 文件服务器地址
     */
    String upload(IPathParams params, String extension, byte[] bytes) throws ServiceException;

    /**
     * 上传文件
     *
     * <pre>
     * fileService.upload(FolderName.files, ".png", input, size);
     * </pre>
     *
     * @param params 文件上传根路径
     * @param extension 文件扩展名, 如.png, 也可以是文件全路径, 会自动截取扩展名
     * @param input 文件流
     * @param size 文件大小
     * @return 文件服务器地址
     */
    String upload(IPathParams params, String extension, InputStream input, long size) throws ServiceException;

    /**
     * 上传文件<br>
     * 如果是临时文件, 移动至params下; 如果是站外文件, 下载另存至params下; 如果是站内文件, 原样返回
     *
     * @param params 文件上传根路径
     * @param url URL路径
     * @return 文件服务器地址
     */
    String upload(IPathParams params, String url) throws ServiceException;

    /**
     * 判断是不是文件服务器内的文件
     * 
     * @param url 文件路径
     * @return 是不是文件服务器内的文件
     * @throws ServiceException
     */
    boolean isInsideFile(String url) throws ServiceException;

    /**
     * 判断是不是临时文件
     * 
     * @param url 文件路径
     * @return 是不是临时文件
     * @throws ServiceException
     */
    boolean isTempsFile(String url) throws ServiceException;

    /**
     * 将path转换为本地绝对对路径, 如果不是本地文件服务则返回null
     * 
     * @param url 原路径
     * @return 本地绝对对路径
     */
    default String toLocalAbsolutePath(String url) {
        return null;
    }

    /**
     * 将文件移动至另一个分组, 一般用于将临时文件移至正式文件根路径<br>
     * 如果不支持移动则返回原路径
     * 
     * @param url 文件路径
     * @param params 文件上传根路径
     * @return 移动后的文件路径
     * @throws ServiceException
     */
    String moveTo(String url, IPathParams params) throws ServiceException;

    /**
     * 删除指定文件
     * 
     * @param url 文件路径
     * @throws ServiceException
     */
    void deleteFile(String url) throws ServiceException;

    /**
     * 文件操作授权
     *
     * @return 文件操作凭证
     * @throws ServiceException
     */
    FileAuthorization authorize() throws ServiceException;

    /**
     * 授权
     *
     * @param params 文件上传根路径
     * @return 文件操作凭证
     * @throws ServiceException
     */
    FileAuthorization authorize(IPathParams params) throws ServiceException;

}
